{"cells": [{"cell_type": "markdown", "metadata": {}, "source": ["# Configuring Location Tracking and Track Views For Your Organization"]}, {"cell_type": "markdown", "metadata": {}, "source": ["<center><img src=\" \" width=500></center>"]}, {"cell_type": "markdown", "metadata": {}, "source": ["\n", "[Location tracking](https://enterprise.arcgis.com/en/portal/latest/administer/windows/configure-location-tracking.htm) is an organization-wide capability, providing the ability to record where users are and where they have been. Location tracking makes use of a feature service that stores tracked locations as point features in the scalable spatiotemporal big data store. The tracks are secure within the location tracking service: users only see their own tracks, with additional permissions required to view the tracks of others. The tracks can be used for situational awareness and for analysis to answer questions related to where users have been.\n", "\n", "[ArcGIS Tracker](https://www.esri.com/en-us/arcgis/products/tracker-for-arcgis/overview) empowers location tracking, using two apps: the **Track Viewer web app** and the **ArcGIS Tracker mobile app**. The Track Viewer web app enables administrators to create track views, defining who is tracked and who can view those tracks. The Tracker mobile app is optimized for tracking locations in the field, running in background while minimizing the impact on device battery. The mobile app records tracks whether or not there is a data connection, and gives mobile users control of when they are and aren't tracked.\n", "\n", "The ArcGIS API for Python makes it easy to manage location tracking capability in an automated, repeatable, and scalable way."]}, {"cell_type": "markdown", "metadata": {}, "source": ["## Configuring Location Tracking\n", "An authenicated administrator is able to configure location tracking via the `LocationTrackingManager`."]}, {"cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": ["import arcgis"]}, {"cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [{"data": {"text/plain": ["['LocationTrackingError',\n", " 'LocationTrackingManager',\n", " 'MobileUserManager',\n", " 'TrackView',\n", " 'TrackViewerManager',\n", " '__builtins__',\n", " '__cached__',\n", " '__doc__',\n", " '__file__',\n", " '__loader__',\n", " '__name__',\n", " '__package__',\n", " '__path__',\n", " '__spec__',\n", " '_errors',\n", " '_location_tracking',\n", " '_track_view']"]}, "execution_count": 2, "metadata": {}, "output_type": "execute_result"}], "source": ["dir(arcgis.apps.tracker)"]}, {"cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": ["from arcgis.gis import GIS\n", "from arcgis.apps.tracker import TrackView\n", "\n", "gis = GIS(profile=\"your_enterprise_portal\")\n", "location_tracking = gis.admin.location_tracking"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Location Tracking has three states `enabled`, `paused`, and `disabled`. It's easy to check the status of Location Tracking."]}, {"cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [{"data": {"text/plain": ["'disabled'"]}, "execution_count": 2, "metadata": {}, "output_type": "execute_result"}], "source": ["location_tracking.status"]}, {"cell_type": "markdown", "metadata": {}, "source": ["An administrator is able to enable location tracking via the `LocationTrackingManager`."]}, {"cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [{"data": {"text/plain": ["True"]}, "execution_count": 3, "metadata": {}, "output_type": "execute_result"}], "source": ["location_tracking.enable()"]}, {"cell_type": "markdown", "metadata": {}, "source": ["When location tracking is enabled, a new item gets created representing the `Location Tracking Feature Service`. Any mobile user can upload their tracks to this service. This item can be easily accessed using the `LocationTrackingManager` object."]}, {"cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [{"data": {"text/html": ["<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://pythonapi.playground.esri.com/portal/home/item.html?id=6c84b709772d4a18ae6eac2cadf7d0c6' target='_blank'>\n", "                        <img src='https://pythonapi.playground.esri.com/portal/portalimages/desktopapp.png' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://pythonapi.playground.esri.com/portal/home/item.html?id=6c84b709772d4a18ae6eac2cadf7d0c6' target='_blank'><b>location_tracking</b>\n", "                        </a>\n", "                        <br/><img src='https://pythonapi.playground.esri.com/portal/home/js/jsapi/esri/css/images/item_type_icons/featureshosted16.png' style=\"vertical-align:middle;\">Feature Layer Collection by apulver\n", "                        <br/>Last Modified: May 02, 2019\n", "                        <br/>0 comments, 0 views\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<Item title:\"location_tracking\" type:Feature Layer Collection owner:apulver>"]}, "execution_count": 4, "metadata": {}, "output_type": "execute_result"}], "source": ["location_tracking.item"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The `Location Tracking Feature Service` has two layers. The first layer,`tracks`, stores the historical breadcrumbs of each user. The second layer, `last_known_locations`, stores the most recent location of each user that is using the Tracker mobile app. These layers can be easily accessed via the `LocationTrackingManager`."]}, {"cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [{"data": {"text/plain": ["<FeatureLayer url:\"https://pythonapi.playground.esri.com/server/rest/services/Hosted/location_tracking/FeatureServer/0\">"]}, "execution_count": 5, "metadata": {}, "output_type": "execute_result"}], "source": ["location_tracking.tracks_layer"]}, {"cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [{"data": {"text/plain": ["<FeatureLayer url:\"https://pythonapi.playground.esri.com/server/rest/services/Hosted/location_tracking/FeatureServer/1\">"]}, "execution_count": 6, "metadata": {}, "output_type": "execute_result"}], "source": ["location_tracking.last_known_locations_layer"]}, {"cell_type": "markdown", "metadata": {}, "source": ["By default, the tracks layer has a retention period of 30 days which means tracks will only be stored for 30 days. An administrator is able to configure the retention period to suit their organization's needs. Let's see how to set the retention period to 6 months."]}, {"cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [], "source": ["location_tracking.retention_period = 6\n", "location_tracking.retention_period_units = \"MONTHS\""]}, {"cell_type": "markdown", "metadata": {}, "source": ["Additionally, if an organization wants to keep their tracks forever, the retention period can be turned off."]}, {"cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [], "source": ["location_tracking.retention_period_enabled = False"]}, {"cell_type": "markdown", "metadata": {}, "source": ["### Creating and Configuring a Track View\n", "A core concept of Location Tracking is that certain users in the organization are able to view the tracks of others. This is accomplished by creating a \"Track View\". A track view is a [feature service view](https://doc.arcgis.com/en/arcgis-online/manage-data/create-hosted-views.htm) created from the Location Tracking Service. It contains a list of Mobile Users representing the users whose tracks will be displayed, and a list of Track Viewers who will have access to see those users tracks. A Track View can easily be created by an administrator."]}, {"cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [], "source": ["track_view = location_tracking.create_track_view(\"Demo Track View\")"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The `create_track_view()` function returns a `TrackView` object. An adminstrator can easily add viewers to the `TrackView`:"]}, {"cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [], "source": ["track_view.viewers.add(['tracker_demo'])"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Similarily an administrator can add mobile users to the Track View"]}, {"cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [], "source": ["track_view.mobile_users.add(['tracker_demo'])"]}, {"cell_type": "markdown", "metadata": {}, "source": ["It's easy to see who the track viewers and mobile users are in a `TrackView`"]}, {"cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [{"data": {"text/plain": ["['tracker_demo', 'apulver']"]}, "execution_count": 12, "metadata": {}, "output_type": "execute_result"}], "source": ["track_view.viewers.list()"]}, {"cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [{"data": {"text/plain": ["['tracker_demo']"]}, "execution_count": 13, "metadata": {}, "output_type": "execute_result"}], "source": ["track_view.mobile_users.list()"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The `TrackView` provides access to both the tracks and last known locations layers so they can easily be used for analysis"]}, {"cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [{"data": {"text/plain": ["<FeatureLayer url:\"https://pythonapi.playground.esri.com/server/rest/services/Hosted/98bebbeb4dcf4bbc942c24c2595fabc2_Track_View/FeatureServer/0\">"]}, "execution_count": 14, "metadata": {}, "output_type": "execute_result"}], "source": ["track_view.tracks_layer"]}, {"cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [{"data": {"text/plain": ["<FeatureLayer url:\"https://pythonapi.playground.esri.com/server/rest/services/Hosted/98bebbeb4dcf4bbc942c24c2595fabc2_Track_View/FeatureServer/1\">"]}, "execution_count": 15, "metadata": {}, "output_type": "execute_result"}], "source": ["track_view.last_known_locations_layer"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Track views can easily be searched for as follows:"]}, {"cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [], "source": ["items = gis.content.search(\"typekeywords:'Location Tracking View'\")"]}, {"cell_type": "markdown", "metadata": {}, "source": ["A `TrackView` object can be created from an item as follows:"]}, {"cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [{"data": {"text/plain": ["<arcgis.apps.tracker._track_view.TrackView at 0x1190c6240>"]}, "execution_count": 17, "metadata": {}, "output_type": "execute_result"}], "source": ["track_view2 = TrackView(items[0])\n", "track_view2"]}, {"cell_type": "markdown", "metadata": {}, "source": ["### Managing Tracker Licenses"]}, {"cell_type": "markdown", "metadata": {}, "source": ["In order to sign into the Tracker mobile app and upload tracks, users must be provisioned an [ArcGIS Tracker](https://www.esri.com/en-us/arcgis/products/tracker-for-arcgis/overview) License.\n", "\n", "We can see how many licenses are available and how many are assigned"]}, {"cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [{"data": {"text/html": ["<div>\n", "<style scoped>\n", "    .dataframe tbody tr th:only-of-type {\n", "        vertical-align: middle;\n", "    }\n", "\n", "    .dataframe tbody tr th {\n", "        vertical-align: top;\n", "    }\n", "\n", "    .dataframe thead th {\n", "        text-align: right;\n", "    }\n", "</style>\n", "<table border=\"1\" class=\"dataframe\">\n", "  <thead>\n", "    <tr style=\"text-align: right;\">\n", "      <th></th>\n", "      <th>Entitlement</th>\n", "      <th>Total</th>\n", "      <th>Assigned</th>\n", "      <th>Remaining</th>\n", "    </tr>\n", "  </thead>\n", "  <tbody>\n", "    <tr>\n", "      <th>0</th>\n", "      <td>tracker</td>\n", "      <td>50</td>\n", "      <td>0</td>\n", "      <td>50</td>\n", "    </tr>\n", "  </tbody>\n", "</table>\n", "</div>"], "text/plain": ["  Entitlement  Total  Assigned  Remaining\n", "0     tracker     50         0         50"]}, "execution_count": 18, "metadata": {}, "output_type": "execute_result"}], "source": ["tracker_license = gis.admin.license.get('ArcGIS Tracker')\n", "tracker_license.report"]}, {"cell_type": "markdown", "metadata": {}, "source": ["An ArcGIS Tracker License can be assigned as follows"]}, {"cell_type": "code", "execution_count": 19, "metadata": {}, "outputs": [{"data": {"text/plain": ["True"]}, "execution_count": 19, "metadata": {}, "output_type": "execute_result"}], "source": ["tracker_license.assign(username='tracker_demo', entitlements=[\"tracker\"])"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Similarily a license could be revoked"]}, {"cell_type": "code", "execution_count": 20, "metadata": {}, "outputs": [{"data": {"text/plain": ["True"]}, "execution_count": 20, "metadata": {}, "output_type": "execute_result"}], "source": ["tracker_license.revoke(username='tracker_demo', entitlements=[\"tracker\"])"]}, {"cell_type": "markdown", "metadata": {}, "source": ["### Managing the \"view location tracks\" privilege"]}, {"cell_type": "markdown", "metadata": {}, "source": ["In order for track viewers to see the tracks of other users in the organization (through a Track View), they must have a role that has the \"view location tracks\" privilege. The administrator role has this privilege by default. Non-administrators will need to be assigned a custom role that has this privilege. A custom role that can view tracks can be created as shown below."]}, {"cell_type": "code", "execution_count": 21, "metadata": {}, "outputs": [], "source": ["track_viewer_role = gis.users.roles.create(\n", "    name='Track Viewer',\n", "    description=\"A user that can use the Track Viewer web app to see others tracks\",\n", "    privileges=[\n", "        \"portal:user:joinGroup\",\n", "        \"portal:user:viewTracks\",\n", "    ]\n", ")"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The custom role can then be assigned to a user."]}, {"cell_type": "code", "execution_count": 22, "metadata": {}, "outputs": [{"data": {"text/plain": ["True"]}, "execution_count": 22, "metadata": {}, "output_type": "execute_result"}], "source": ["user = gis.users.get('tracker_demo')\n", "user.update_role(track_viewer_role)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["## Conclusion\n", "This guide explains how an administrator can enable the location tracking capability, and once enabled, how track views can be created and users be added to it. It also explains how an administrator can assign licenses for the Tracker field app to desired users and how custom roles with privileges to view tracks of other users be created."]}], "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.4"}}, "nbformat": 4, "nbformat_minor": 2}